\chapter{geomagick HOWTO}

This HOWTO is supposed to give a very practical and easy to understand introduction
to using geomagick. It is however assumed, that your familiar with your operating system. Even
tough \emph{cmake}, the build-system used to build \emph{geomagick}, supports \emph{Visual-C++} 
natively, it is strongly recommended to use a unix-like-environment like \emph{cygwin} when working on \emph{windows}.
Not only will \emph{cygwin} save the windows user from the \emph{dependency-hell} with its
large repository of packages that can easily be installed as required, but also will the
build procedure be exactly the same as on any other system. 


\section{Getting and Building geomagick}
\subsection{Preparation}
It is essential that your system meets all dependencies before you start building
the libraries. First of all \emph{geomagick} requires a couple of build tools to be 
installed.
\subsubsection{Build Tools}
Namely, it requires \emph{cmake}, a \emph{C/C++} compiler-environment supported by \emph{cmake}.
Preferably, \emph{gcc/g++} is used for building. In conjuction with \emph{gcc/g++}, \emph{cmake}
will also need \emph{GNU Make}. So please make sure that your basic build system has been installed
successfully, before you continue.

\subsubsection{Required libraries}
Next, a couple of libraries should be installed in adittion to the \emph{C/C++ standard libraries}.
Most impportantly, \emph{boost-C++} is required, as \emph{geomagick} is heavily based on it. In order
to support \emph{NURBS}, the library \emph{nurbs++} is required. Optionally you might also want to have
\emph{OpenGL} installed. \emph{OpenGL} will allow you to display geometric data, what can be really
helpful, when debugging your own code.

\subsection{Downloading geomagick}
The current version of \emph{geomagick} can be retrieved from the subversion
repository. Once subversion is installed on your system, change to the directory in
which you would like to have the geomagick sources and type the following line.
\begin{lstlisting}
svn checkout http://geomagick.googlecode.com/svn/trunk/ geomagick
\end{lstlisting}
This will create a new subfolder in your current workin directory and download
the current sources of \emph{geomagick}.

\subsection{Building geomagick}
After downloading geomagick successfully, change to the newly created directory.
\begin{lstlisting}
cd geomagick
\end{lstlisting}
Then type.
\begin{lstlisting}
cmake .
\end{lstlisting}
This will create the make files. Pleas read the command line output carefully.
It will tell you, whether all libraries and build tools have been installed on
your system. On success you can start building the library.
\begin{lstlisting}
make
\end{lstlisting}
That's it.

\section{Doing a simple conversion}
The source code listed below shows how to do a conversion using geomagick. 
the source code starts with instatiating a \emph{ConversionManager}(line 11). Using the
instatce of the \emph{ConversionManager}, a \emph{ConversionRoute} can be retrieved
 (line 25). Finally, the \emph{ConversionRoute} is used on data acquired previously
to do a conversion (line 36).
\lstset{
language=C++,
showspaces=false,
tabsize=2,
basicstyle=\small\sffamily,
keywordstyle=\color{blue}\bfseries,
showstringspaces=false,
numbers=left,
captionpos=b 
}

\begin{lstlisting}
#include <iostream>
#include <fstream>
#include <geomagick>

using namespace geomagick;

int main(int, char *[])
{
      
      //Create a new ConversionManager
      ConversionManager * TestManager = new ConversionManager();

      // Put the Source Types from which we want to convert into a
      // Vector. We do not yet need any geometric data or Instances
      // of any Basetypes.
      vector<BaseTypeId*> SourceType;	
            SourceType.push_back(Polygons::getTypeId());
		
      // The Target Types are set up like the Source Types
      vector<BaseTypeId*> TargetType;
            TargetType.push_back(Triangles::getTypeId());
            TargetType.push_back(Nurbs::getTypeId());

      // All that needs to be done in order to get a Conversion Route.
      ConversionRoute CR = TestManager->route(SourceType,TargetType);
      
      // We might want to print the conversion Route to stdout.
      CR.print();

      // Now you read geometric data. In your project you will probably
      // already have the geometric data avialable in some form.
      Polygons* testPolygons = readObj();

      // Finally we do the actual conversion by simply calling the process
      // attribute of the previously calculated Conversion Route.
      Triangles* testTriangles =  (Triangles*)CR.process(testPolygons);

      return 0;
}      
\end{lstlisting}


\section{Using geomagick to convert from and to custom data types}
\subsection{Creating a new BaseType}

\begin{lstlisting}

\end{lstlisting}

\subsection{Creating a new Conversion}

\begin{lstlisting}

\end{lstlisting}

\subsubsection{ConversionWeight}

\subsection{Registering custom BaseTypes and Conversions}

\begin{lstlisting}

\end{lstlisting}

\section{Displaying Data}

Displaying is currently implemented for the types Triangles and Polygons as well as
for the type NURBS. 


